<?php
// $Id$
/**
 * This file contains {@link PropertyDef} which is part of the PHP Content 
 * Repository (phpCR), a derivative of the Java Content Repository JSR-170,  
 * and is licensed under the Apache License, Version 2.0.
 *
 * This file is based on the code created for
 * {@link http://www.jcp.org/en/jsr/detail?id=170 JSR-170}
 *
 * @author Travis Swicegood <travis@domain51.net>
 * @copyright PHP Code Copyright &copy; 2004-2005, Domain51, United States
 * @copyright Original Java and Documentation 
 *  Copyright &copy; 2002-2004, Day Management AG, Switerland
 * @license http://www.apache.org/licenses/LICENSE-2.0 Apache License, 
 *      Version 2.0
 * @package phpContentRepository
 */

/**
 * Load the {@link phpCR} library file(s)
 */ 
require_once(dirname(__FILE__) . '/../phpCR.library.php');

phpCR::loadInterface('NodeType', '/nodetype');
phpCR::loadInterface('Value');

if (phpCR::getLevel() >= 2) {
    phpCR::loadClass('OnParentVersionAction', '/version');
}


/**
 * A {@link Property} definition. Used in {@link Node} type definitions.
 *
 * @author PHP - Travis Swicegood <travis@domain51.net>
 * @copyright Copyright &copy; 2004-2005, Domain51
 * @package phpContentRepository
 */
interface PropertyDef 
{
   /**
    * Gets the {@link NodeType} that contains the declaration of this
    * {@link PropertyDef}.
    *
    * @return object
    *   A {@link NodeType} object.
    */
    public function getDeclaringNodeType();
    
    
   /**
    * Gets the name of the {@link Property} that this definition applies to.
    *
    * If NULL, then this {@link PropertyDef} defines a residual
    * set of {@link Property}s. That is, it defines the characteristics of all 
    * those {@link Property}s with names apart from the names explicitly used in
    * other {@link Property} or child {@link NodeDef}s.
    *
    * @return string|null
    */
    public function getName();
    
    
   /**
    * Gets the required type of the {@link Property}. One of:
    * <ul>
    *   <li>{@link PropertyType::STRING}</li>
    *   <li>{@link PropertyType::DATE}</li>
    *   <li>{@link PropertyType::BINARY}</li>
    *   <li>{@link PropertyType::DOUBLE}</li>
    *   <li>{@link PropertyType::LONG}</li>
    *   <li>{@link PropertyType::BOOLEAN}</li>
    *   <li>{@link PropertyType::SOFTLINK}</li>
    *   <li>{@link PropertyType::REFERENCE}</li>
    *   <li>{@link PropertyType::UNDEFINED}</li>
    * </ul>
    *
    * {@link PropertyType::UNDEFINED} is returned if this {@link Property} may
    * be of any type.
    *
    * @return int
    */
    public function getRequiredType();
    
    
   /**
    * Gets the constraint string. This string describes the constraints
    * that exist on future values of the {@link Property}.
    *
    * Reporting of value constraints is optional. An implementation
    * is free to return NULL to this call, indicating that value
    * constraint information is unavailable (though a constraint may still
    * exist).
    *
    * If a string is returned then it is interpreted in different ways
    * depending on the type specified for this {@link Property}. The following
    * describes the value constraint syntax for each {@link Property} type:
    *
    * <dl>
    *   <dt>{@link PropertyType::STRING}</dt>
    *   <dd>The constraint string is a regular expression pattern. For example 
    *       the regular expression ".*" means any string".  See
    *       {@link http://www.php.net/preg_match} for full explanations of 
    *       regular expressions inside PHP.</dd>
    *
    *   <dt>{@link PropertyType::REFERENCE}</dt>
    *   <dd>The constraint string is a comma separated list of {@link NodeType}
    *       names. For example "nt:authored, mynt:newsArticle".</dd>
    *
    *   <dt>{@link PropertyType::BOOLEAN}</dt>
    *   <dd>Either TRUE or FALSE.</dd>
    * </dl>
    *
    * The remaining types all have value constraints in the form of inclusive
    * or exclusive ranges: i.e., "[min, max]",
    * "(min, max)", "(min, 
    * max]" or "[min, max)". 
    * Where "[" and "]" indicate "inclusive", while
    * "(" and ")" indicate "exclusive". 
    *
    * A missing min or max value
    * indicates no bound in that direction. For example [,5]
    * means no minimum but a maximum of 5 (inclusive).
    * The syntax and meaning of the min and 
    * max values themselves differs between types as 
    * follows:
    *
    * <dl>
    *   <dt>{@link PropertyType::BINARY}</dt>
    *   <dd>min and max specify the 
    *       allowed size range of the binary value in bytes.</dd>
    *
    *   <dt>{@link PropertyType::DATE}</dt>
    *   <dd>min and max are dates
    *       specifiying the allowed date range. The date strings must be in the
    *       ISO8601-compliant format: 
    *       YYYY-MM-DDThh:mm:ss.sssTZD.</dd>
    *
    *   <dt>{@link PropertyType::LONG}, {@link PropertyType::INT}, 
    *       {@link PropertyType::FLOAT}, {@link PropertyType::DOUBLE}</dt>
    *   <dd>min and max are 
    *       numbers.</dd>
    * </dl>
    *
    * @return string|null
    */
    public function getValueConstraint();
    
    
   /**
    * Gets the default value of the {@link Property}. 
    *
    * This is the value that the {@link Property} will be assigned if it is
    * either automatically created, or created without a specified initial 
    * value.
    *
    * If NULL, then the {@link Property} has no fixed default 
    * value. Note that this does not exclude the possibility that the 
    * {@link Property} still assumes some value automatically, but that value 
    * may be variable (for example, "the current date") and hence cannot be
    * expressed as a single fixed value.
    *
    * @return object|null
    */
    public function getDefaultValue();
    
    
   /**
    * Reports whether the {@link Property} is to be automatically created when
    * its parent {@link Node} is created.
    *
    * If TRUE then this {@link PropertyDef} will necessarily  not 
    * be a residual set definition but will specify an actual {@link Property} 
    * name (in other words {@link getName()} will return a non-null value).
    *
    * @return bool
    */
    public function isAutoCreate();
    
    
   /**
    * Reports whether the {@link Property} is mandatory. 
    *
    * A mandatory {@link Property} is one that, if its parent {@link Node}
    * exists, must also exist. It cannot be removed through this API except by
    * removing its parent. An attempt to save a {@link Node} that has a 
    * mandatory {@link Property} without first creating that {@link Property},
    * will throw a {@link ConstraintViolationException} on {@link Node::save()}.
    *
    * If a {@link Property} is mandatory then the following restrictions must be
    * enforced:
    * <ul>
    *   <li>If autoCreate is FALSE then the client 
    *       must ensure that the {@link Property} is created (and if no default 
    *       value is indicated, given a value) before the parent {@link Node} is 
    *       saved, otherwise a {@link ConstraintViolationException} will be 
    *       thrown on {@link Node::save()}.</li>
    *   <li>Once created, the {@link Property} cannot be removed without 
    *       removing its parent {@link Node}, otherwise a 
    *       {@link ConstraintViolationException} is thrown on 
    *       {@link Node::save()}.</li>
    * </ul>
    *
    * @return bool
    */
    public function isMandatory();
    
    
   /**
    * Gets the on-parent-version status of the {@link Property}.
    *
    * This governs what to do if the parent {@link Node} of this 
    * {@link Property} is versioned; an {@link OnParentVersionAction}.
    *
    * @return int
    */
    public function getOnParentVersion();
    
    
   /**
    * Reports whether the {@link Property} is read-only.
    *
    * A read-only {@link Property} cannot be written-to via this API. It may be 
    * written to, however, by the implementation itself via some mechanism not
    * specified by this specification.
    *
    * @return bool
    */
    public function isReadOnly();
    
    
   /**
    * Reports whether this {@link Property} is the primary child item of its
    * parent {@link Node}. 
    *
    * Since any given {@link Node} may have either zero or one primary child
    * {@link Item}s, this means that a maximum of one {@link PropertyDef} or
    * {@link NodeDef} within a particular {@link NodeType} may return 
    * TRUE on this call. 
    *
    * The primary child item flag is used by the method 
    * {@link Node::getPrimaryItem()}.
    *
    * @return bool
    */
    public function isPrimaryItem();
    
    
   /**
    * Reports whether this {@link Property} can have multiple values.
    *
    * @return bool
    */
    public function isMultiple();
}

